topsql: document detailed TiKV I/O dimensions by jiong-nba · Pull Request #23532 · pingcap/docs

jiong-nba · 2026-08-14T10:15:13Z

What is changed, added or deleted? (Required)

Document the detailed TiKV I/O dimensions available in Top SQL starting from TiDB v8.5.9, including the switch dependency, UI behavior, compatibility fallback, overhead, and troubleshooting.
Document resource-metering.enable-detailed-io-collection in the TiKV configuration reference with a v8.5.9 version marker.
Clarify that Read IOPS is a foreground RocksDB block-read attribution signal rather than device-level IOPS.
Refresh six Top SQL screenshots to cover the detailed I/O setting, aggregation and sorting controls, chart, SQL details, and database aggregation result.

Which TiDB version(s) do your changes apply to? (Required)

Tips for choosing the affected version(s):

By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.

For details, see tips for choosing the affected versions.

What is the related PR or file link(s)?

This PR is translated from: topsql: document detailed TiKV I/O dimensions docs-cn#21886
Other reference link(s):
- Tracking issue: Extend Top SQL resource dimensions with logical read/write and RocksDB block reads tikv/tikv#19867
- TiKV: *: extend Top SQL resource dimensions tikv/tikv#19953
- kvproto: resource_usage_agent: add RocksDB block read count to Top SQL resource dimensions kvproto#1498
- TiDB Dashboard: topsql: support detailed TiKV IO dimensions tidb-dashboard#1917
- ng-monitoring: topsql: support detailed IO dimensions ng-monitoring#355

AI agent involvement

The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

Delete files
Change aliases
Need modification after applied to another branch
Might cause conflicts after applied to another branch

Summary by CodeRabbit

New Features
- Top SQL now supports separate sorting dimensions for logical reads, logical writes, and read IOPS.
- Added configuration guidance for enabling detailed TiKV I/O collection.
Documentation
- Updated Top SQL usage instructions, feature descriptions, screenshots, scenarios, and FAQs.
- Documented configuration prerequisites, default behavior, and available I/O metrics.

Signed-off-by: jiong-nba <jiongnba@gmail.com>

ti-chi-bot · 2026-08-14T10:15:16Z

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

ti-chi-bot · 2026-08-14T10:15:21Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign lance6716 for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

coderabbitai · 2026-08-14T10:15:22Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ec2fd342-155a-4dc6-a533-fb468d7c33d1

📥 Commits

Reviewing files that changed from the base of the PR and between 97bbec4 and 22efc30.

⛔ Files ignored due to path filters (6)

media/dashboard/v8.5.9-top-sql-details.png is excluded by !**/*.png
media/dashboard/v8.5.9-top-sql-settings-enable-detailed-io.png is excluded by !**/*.png
media/dashboard/v8.5.9-top-sql-usage-agg-by-db-detail.png is excluded by !**/*.png
media/dashboard/v8.5.9-top-sql-usage-chart.png is excluded by !**/*.png
media/dashboard/v8.5.9-top-sql-usage-select-agg-by.png is excluded by !**/*.png
media/dashboard/v8.5.9-top-sql-usage-select-order-by.png is excluded by !**/*.png

📒 Files selected for processing (2)

dashboard/top-sql.md
tikv-configuration-file.md

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

📝 Walkthrough

Walkthrough

The documentation adds detailed TiKV I/O dimensions for Top SQL, documents the related TiKV configuration, updates usage instructions and screenshots, describes disabling behavior, and expands FAQ coverage.

Changes

Detailed TiKV I/O dimensions

Layer / File(s)	Summary
Dimension definition and enablement `dashboard/top-sql.md`, `tikv-configuration-file.md`	Documents logical read, logical write, and Read IOPS dimensions, their prerequisites, semantics, overhead, settings, and TiKV configuration.
Usage and toggle behavior `dashboard/top-sql.md`	Updates usage steps and screenshots. Documents replacement of `Order By Logical IO` when detailed dimensions are enabled and restoration when disabled.
FAQ and operational requirements `dashboard/top-sql.md`	Adds dimension meanings and documents reporting overhead, node-wide enablement requirements, and configuration checks.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 22efc

This PR updates Top SQL and TiKV configuration documentation and related screenshots; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: qiancai, lilin90

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely identifies the main change: documenting detailed TiKV I/O dimensions for Top SQL.
Description check	✅ Passed	The description follows the repository template. It explains the changes, lists the affected TiDB versions, provides related links, records AI involvement, and completes the change-type checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Signed-off-by: jiong-nba <jiongnba@gmail.com>

jiong-nba · 2026-08-17T07:19:32Z

End-to-end verification

Verified locally on August 17, 2026 with TiUP, ng-monitoring PR #355 (d295da59), TiDB Dashboard PR #1917 (a70560af source), and TiKV PR #19953 commit d14cd3194.

TiKV HEAD blocker: PR #19953 HEAD 00a1af385 changes kvproto to merged commit af1ad1be, which also introduces ApiVersion::V3. The current TiKV api_version crate has seven non-exhaustive matches and cannot build at that HEAD. The end-to-end run therefore uses d14cd3194, the latest buildable feature commit in the same PR, with its feature-branch kvproto dependency.

TiKV configuration: enable-network-io-collection: true and enable-detailed-io-collection: true
ng-monitoring health check: {"health":true}
Sustained workload: six concurrent query/update patterns for five minutes, completing 4,382 statements
The chart contains continuous per-second samples across the full five-minute window instead of a one-time spike
Leading query attribution:
- Logical Read: 45.85 GiB
- Logical Write: 241.94 MiB
- Read IOPS: 2.80M
Dashboard shows Logical Read, Logical Write, and Read IOPS independently. The legacy combined Logical IO option is hidden while detailed I/O is enabled.

Settings and dimensions

Sustained Logical Read

Sustained Logical Write

Sustained Read IOPS

Signed-off-by: jiong-nba <jiongnba@gmail.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

topsql: document detailed TiKV I/O dimensions

0ebc990

Signed-off-by: jiong-nba <jiongnba@gmail.com>

ti-chi-bot Bot added first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. labels Aug 14, 2026

ti-chi-bot Bot added missing-translation-status This PR does not have translation status info. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 14, 2026

jiong-nba mentioned this pull request Aug 17, 2026

cloud: document detailed Top SQL I/O dimensions #23539

Open

12 tasks

topsql: add detailed I/O screenshots

06a9c9e

Signed-off-by: jiong-nba <jiongnba@gmail.com>

jiong-nba added 2 commits August 17, 2026 15:47

topsql: retain historical screenshots

3b80fcd

Signed-off-by: jiong-nba <jiongnba@gmail.com>

topsql: refresh screenshots with sustained workload

a67fa01

Signed-off-by: jiong-nba <jiongnba@gmail.com>

jiong-nba mentioned this pull request Aug 17, 2026

topsql: document detailed TiKV I/O dimensions pingcap/docs-cn#21886

Open

12 tasks

topsql: correct detailed I/O availability version

22efc30

Signed-off-by: jiong-nba <jiongnba@gmail.com>

jiong-nba added the needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. label Aug 28, 2026

jiong-nba marked this pull request as ready for review August 28, 2026 09:25

Copilot AI lite review requested due to automatic review settings August 28, 2026 09:25

ti-chi-bot Bot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Aug 28, 2026

Copilot AI reviewed Aug 28, 2026

Navigation Menu

Uh oh!

topsql: document detailed TiKV I/O dimensions - #23532

topsql: document detailed TiKV I/O dimensions#23532
jiong-nba wants to merge 5 commits into
pingcap:masterfrom
jiong-nba:codex/topsql-detailed-io-docs

jiong-nba commented Aug 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

ti-chi-bot Bot commented Aug 14, 2026

Uh oh!

ti-chi-bot Bot commented Aug 14, 2026

Uh oh!

coderabbitai Bot commented Aug 14, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

jiong-nba commented Aug 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jiong-nba commented Aug 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is changed, added or deleted? (Required)

Which TiDB version(s) do your changes apply to? (Required)

What is the related PR or file link(s)?

AI agent involvement

Do your changes match any of the following descriptions?

Summary by CodeRabbit

Uh oh!

ti-chi-bot Bot commented Aug 14, 2026

Uh oh!

ti-chi-bot Bot commented Aug 14, 2026

Uh oh!

coderabbitai Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

jiong-nba commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

End-to-end verification

Settings and dimensions

Sustained Logical Read

Sustained Logical Write

Sustained Read IOPS

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jiong-nba commented Aug 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 14, 2026 •

edited

Loading

jiong-nba commented Aug 17, 2026 •

edited

Loading